Next: , Previous: Bus names, Up: Inspection

2.2 Knowing the details of D-Bus services.

D-Bus services publish their interfaces. This can be retrieved and analyzed during runtime, in order to understand the used implementation.

The resulting introspection data are in XML format. The root introspection element is always a node element. It might have a name attribute, which denotes the (absolute) object path an interface is introspected.

The root node element may have node and interface children. A child node element must have a name attribute, this case it is the relative object path to the root node element.

An interface element has just one attribute, name, which is the full name of that interface. The default interface ‘org.freedesktop.DBus.Introspectable’ is always present. Example:

     <node name="/org/bluez">
       <interface name="org.freedesktop.DBus.Introspectable">
         ...
       </interface>
       <interface name="org.bluez.Manager">
         ...
       </interface>
       <interface name="org.bluez.Database">
         ...
       </interface>
       <interface name="org.bluez.Security">
         ...
       </interface>
       <node name="service_audio"/>
       <node name="service_input"/>
       <node name="service_network"/>
       <node name="service_serial"/>
     </node>

Children of an interface element can be method, signal and property elements. A method element stands for a D-Bus method of the surrounding interface. The element itself has a name attribute, showing the method name. Children elements arg stand for the arguments of a method. Example:

     <method name="ResolveHostName">
       <arg name="interface" type="i" direction="in"/>
       <arg name="protocol" type="i" direction="in"/>
       <arg name="name" type="s" direction="in"/>
       <arg name="aprotocol" type="i" direction="in"/>
       <arg name="flags" type="u" direction="in"/>
       <arg name="interface" type="i" direction="out"/>
       <arg name="protocol" type="i" direction="out"/>
       <arg name="name" type="s" direction="out"/>
       <arg name="aprotocol" type="i" direction="out"/>
       <arg name="address" type="s" direction="out"/>
       <arg name="flags" type="u" direction="out"/>
     </method>

arg elements can have the attributes name, type and direction. The name attribute is optional. The type attribute stands for the signature of the argument in D-Bus. For a discussion of D-Bus types and their Lisp representation see Type Conversion.1 The direction attribute of an arg element can be only ‘in’ or ‘out’; in case it is omitted, it defaults to ‘in’.

A signal element of an interface has a similar structure. The direction attribute of an arg child element can be only ‘out’ here; which is also the default value. Example:

     <signal name="StateChanged">
       <arg name="state" type="i"/>
       <arg name="error" type="s"/>
     </signal>

A property element has no arg child element. It just has the attributes name, type and access, which are all mandatory. The access attribute allows the values ‘readwrite’, ‘read’, and ‘write’. Example:

     <property name="Status" type="u" direction="read"/>

annotation elements can be children of interface, method, signal, and property elements. Unlike properties, which can change their values during lifetime of a D-Bus object, annotations are static. Often they are used for code generators of D-Bus langugae bindings. Example:

     <annotation name="de.berlios.Pinot.GetStatistics" value="pinotDBus"/>

Annotations have just name and value attributes, both must be strings.

— Function: dbus-introspect bus service path

This function returns all interfaces and sub-nodes of service, registered at object path path at bus bus.

bus must be either the symbol :system or the symbol :session. service must be a known service name, and path must be a valid object path. The last two parameters are strings. The result, the introspection data, is a string in XML format. Example:

          (dbus-introspect
            :system "org.freedesktop.Hal"
            "/org/freedesktop/Hal/devices/computer")

          ⇒ "<!DOCTYPE node PUBLIC
              "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
              "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
              <node>
                <interface name="org.freedesktop.Hal.Device">
                  <method name="GetAllProperties">
                    <arg name="properties" direction="out" type="a{sv}"/>
                  </method>
                  ...
                  <signal name="PropertyModified">
                    <arg name="num_updates" type="i"/>
                    <arg name="updates" type="a(sbb)"/>
                  </signal>
                </interface>
                ...
              </node>"

This example informs us, that the service ‘org.freedesktop.Hal’ at object path ‘/org/freedesktop/Hal/devices/computer’ offers the interface ‘org.freedesktop.Hal.Device’ (and 2 other interfaces not documented here). This interface contains the method ‘GetAllProperties’, which needs no input parameters, but returns as output parameter an array of dictionary entries (key-value pairs). Every dictionary entry has a string as key, and a variant as value.

The interface offers also a signal, which returns 2 parameters: an integer, and an array consisting of elements which are a struct of a string and 2 boolean values.2

— Function: dbus-introspect-xml bus service path

This function has the same intention as function dbus-introspect. The returned value is a parsed XML tree, which can be used for further analysis. Example:

          (dbus-introspect-xml
            :session "org.freedesktop.xesam.searcher"
            "/org/freedesktop/xesam/searcher/main")

          ⇒ (node ((name . "/org/freedesktop/xesam/searcher/main"))
               (interface ((name . "org.freedesktop.xesam.Search"))
                 (method ((name . "GetHitData"))
                   (arg ((name . "search") (type . "s") (direction . "in")))
                   (arg ((name . "hit_ids") (type . "au") (direction . "in")))
                   (arg ((name . "fields") (type . "as") (direction . "in")))
                   (arg ((name . "hit_data") (type . "aav") (direction . "out")))
                 )
                 ...
                 (signal ((name . "HitsAdded"))
                   (arg ((name . "search") (type . "s")))
                   (arg ((name . "count") (type . "u")))
                 )
               )
               ...
             )
— Function: dbus-introspect-get-attribute object attribute

It returns the attribute value of a D-Bus introspection object. object can be every subtree of a parsed XML tree as retrieved with dbus-introspect-xml. attribute must be a string according to the attribute names in the D-Bus specification. Example:

          (dbus-introspect-get-attribute
            (dbus-introspect-xml :system "org.freedesktop.SystemToolsBackends"
              "/org/freedesktop/SystemToolsBackends/UsersConfig")
            "name")

          ⇒ "/org/freedesktop/SystemToolsBackends/UsersConfig"

If object has no attribute, the function returns nil.

Footnotes

[1] D-Bus signatures are explained in the D-Bus specification http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures.

[2] The interfaces of the service ‘org.freedesktop.Hal’ are described at http://people.freedesktop.org/~david/hal-spec/hal-spec.html#interfaces.